<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <link rel="stylesheet" type="text/css" href="style.css" />
    <title>Reporting Cygwin Problems</title>
  </head>

<body>
<!--#include virtual="navbar.html" -->
<div id="main">
<!--#include virtual="top.html" -->

<h1>Reporting Problems</h1>
<p>Problems?  Problems?  Impossible!</p>

<p>Well, maybe not...  We'd like to hear what you've uncovered but it's
in your best interests to do some initial research.</p>

<p>First, you need to verify that your potential problem hasn't already been
reported by reading the <a href="faq.html">Cygwin FAQ</a> and the <a
href="https://cygwin.com/ml/cygwin/">mailing list archives</a>.  If your
issue is still unresolved, feel free to write to the cygwin list with
your problem.</p>

<p>Before you start asking questions please take a moment to read and
understand some very good general advice on how to ask <a
href="http://www.catb.org/~esr/faqs/smart-questions.html">smart
questions</a>.  Once you've followed that link and read the advice,
please demonstrate that you've actually <em>gained some smartness</em>
by <b>not</b> sending your Cygwin question to the authors at the link.  That
would be a really <b><em>stupid </em></b> thing to do.</p>

<p>For Cygwin advice please come back <b><a
href="problems.html">here</a></b>.</p>

<p>It is not always easy to figure out when you have a user problem and
when you've found a valid Cygwin bug.  If you have tracked things down
as far as verifying to yourself that you've found a bug, please consider
investigating it yourself and sending us patches if you figure out a
solution.  Bug reports without solutions are also ok, of course,
although if you <em>really</em> want a bug fixed you can exercise the
power implicit in free software and provide the patch yourself.</p>

<p>Otherwise, if you can't determine if you've discovered a bug or just are
having problems that require help, send a <a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"><em>detailed description</em></a>
(with a test case if possible) to the <a href="lists.html">
appropriate mailing list</a> after reading all of problem reporting
guidelines on this page.  Due to the mailing list volume, we don't
always reply to individual reports sent to the list but we do keep track
of them.</p>

<h3><a id="personal-email">
Shouldn't I just send email to straight to a Cygwin developer or package maintainer?</a>
  <blockquote class="smaller">
    <div class="smaller">
	Isn't personal email more efficient than using a mailing list?&nbsp;&nbsp; <em>or</em><br/>
	I don't want to bother the list with my problem.&nbsp;&nbsp;<em>or</em><br/>
	I'm not really sure if this is a real problem and want to find out before I bother the list.
    </div>
</blockquote>
</h3>

<p>Using the correct Cygwin mailing list is absolutely the proper way
to report problems or make observations.  The mailing lists were created for this express
purpose.  Reporting problems to a public forum means that the workload
is shared and, since your report will be read by many people, it may
get more attention than one person would be able to provide.</p>

<p>So, there is generally no need to "Cc" a package maintainer with your
observations.  All maintainers should be reading the appropriate mailing list
so Ccing them will result in sending them two copies of your email.</p>

<p>This is <em>particularly</em> true if you notice that someone has
<em>specifically</em> set the <tt>Reply-To</tt> of a message to go only
to the cygwin mailing list.  Some contributors even take this a step
further and actually set their return address to
the mailing list in an attempt to make it very obvious that
Cygwin-related email should go to the mailing list.</p>

<p>Nevertheless, some people still seem to insist on either Cc'ing
Cygwin contributors or sending private email.  This is inconsiderate.
Please <b>do not do this</b> unless specifically requested.</p>
<div class="background">
<b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
<h2>Reporting guidelines</h2>
<b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<ul class="spaced">
<li>Use a subject line that describes the issue well:

<div class="indent">
<br/>Good examples:<br/>
<blockquote>
	"1.7.10: possible Cygwin DLL select bug (W7 and XP)" <br/>
	"problem with open() in perl 5.14.1-2"<br/>
	"question about cat'ing binary files in bash"
</blockquote>

Bad examples:<br/>
<blockquote>
	"question?"<br/>
	"bug"<br/>
	"porting problem"<br/>
	"help!!!!"<br/>
	"bash question"<br/>
	"newbie needs help"<br/>
	"Question for Jane Simmons"<br/>
	"make"<br/>
	"gcc"<br/>
	"grep"<br/>
	(basically any single word subject)
</blockquote>
</div>

This also applies to general non-problem-related discussion.  It's very hard to follow
the list when most of the subject lines look very similar.
</li>

<li>When reporting problems, <em>describe the problem</em> rather than
just including your interpretation of the problem.

<div class="indent">
<br/>Bad example:<br/>
<blockquote>
	"Cygwin's setup.exe fails to operate when the humidity is high.
	How can I solve Cygwin's problem with high humidity?"
</blockquote>

Good example:<br/>
<blockquote>
	"I'm noticing this summer, that whenever I try to install Cygwin,
	setup.exe dies with a fatal exception at NNNNNN.  Could this
	be a problem with humidity?"
</blockquote>
</div>
</li>


<a id="cygcheck">
<li><b>Run <tt>cygcheck -s -v -r &gt; cygcheck.out</tt> and include that file as

<em>an attachment</em> in your report.  Please do <em>not</em> compress or
otherwise encode the output.  Just attach it as a straight text file so
that it can be easily viewed.</b>
<br/><br/>Note: It is ok to redact sensitive information like username and to remove
site-specific environment variables but please note that fact in your email message
so that we'll know that the cygcheck output has been modified.
</li>


<a id="xwin-log">
<li>Similarly, if your problem involves the Cygwin/X server, include the file
<tt>/var/log/xwin/XWin.0.log</tt> in addition to your cygcheck output as 
<em>plain-text attachments</em> in your report.</li>

<a id="the-problem">
<li>Do not assume that your problem is so trivial or so

"well known" that it does not require any details or background from
you.  Many (most?) people who report problems fall into the trap of
assuming that people are "clued into" their mental state when, in most
cases, this is not the case.

<br/><br/>As a rule of thumb, if you find yourself referring to your problem as
<em>the</em> problem with <tt>XYZ</tt> rather than <em>a</em> problem
with <tt>XYZ</tt> then your message is suspect.  Using <em>the</em> in
this context means that you are assuming that your problem is well known.
Unless you can point to an email message thread or FAQ entry (either of which
is a good idea, btw) please do not assume that the readers of your message will
be familiar with your problem.</li>

<li>If you are experiencing problems with a package which is not part of
the <a href="packages/">Cygwin distribution</a> first see if there is a
better forum available for discussing it.  Don't expect that just
because you are having problems with a package <em>on</em> Cygwin that
there is a problem <em>with</em> Cygwin.  If you truly think that this
is a generic problem with Cygwin, then <em>explain</em> what the package
is and where it came from rather than expecting people to "just
know".</li>

<li>Try to confine your email to one problem per message.  Do not reuse
previous subjects to report unrelated problems.</li>

<li><em>Reply</em> to the email in the thread that you started rather
than creating a new message for each reply.  If you just send a new
message every time you want to offer something about your problem, you
will confuse people who want to help but are expecting the discussion
to occur in the thread that you created.</li>

<li>In your (detailed) description, show how to reproduce the problem.
This means including a test case if at all possible.</li>

<li>If you can't run cygcheck for some reason (and why shouldn't you be
able to?  cygcheck is just a standard windows program which does not use
the Cygwin dll), at the very least, explain <em>why</em> you can't use
cygcheck, include the Cygwin release
you are using, and give the operating system and its version number:
e.g.  "Cygwin v1.7.8 under Windows 7".</li>

<li>Avoid the use of exclamation marks or multiple question marks.  They
add nothing to the report and provide the impression that you are too
excited to think calmly about the problem.</li>

<li>Avoid personal details about why you need the problem rectified,
how important it is for you to have it fixed, or how long you've worked
on it.  People will be more likely to look at your email if it
is cut and dry, to the point, and uses a minimum of extra
words.</li>

<li>Avoid expressions of incredulity like "I can't believe that this is so broken!"
or other editorializing.</li>

<li>Minimize reporting that your problem "works fine" on some "other" UNIX platform or
used to work ok in a previous Cygwin release.  This is marginally useful data but
it does not <em>guarantee</em> that you've uncovered a Cygwin problem.
Cygwin can change its behavior between releases; sometimes to fix an
operational problem and sometimes, well... because we've introduced a bug.

<br/><br/>With regard to differing behavior from some flavor of UNIX:
UNIXes vary in their behavior and Cygwin is basically a different flavor of UNIX.
One common source of differing behavior is with programs which rely on specific
malloc behavior, like being able to free a pointer twice or being able to
access memory after freeing.  Cygwin is unforgiving about this kind of practice
while some older linux versions of malloc are not.

<br/><br/>Note that, "It worked in a previous version of Cygwin" observations are only
relevant for modern versions of Cygwin.  The "B series" versions of Cygwin
(B17, B18, B19, B20) are not modern versions.  Save your fingers and don't
even bother with comments about your experiences with these versions.

<br/><br/>Many people seem to latch onto the fact that their issues do not seem to
occur in other versions of UNIX or Cygwin and mention this in
all followup email when people attempt to help them with the problem.
However, this information is usually only useful in the first message
and does not usually bear repeating.</li>

<li>Keep in mind that there are over 1500 people on the mailing list.  Try
to avoid "me too" responses or reporting problems that have already been
reported.  It's hard enough keeping up with the volume as it is...</li>

<li><a href="contrib.html">Send a patch</a> to fix the problem if you can.</li>
</ul>
</div>
<div id="footer">
<p>UNIX&reg; is a registered trademark of the Open Group in the United States and other countries.</p>
</div>
</body>
</html>
